From: Richard Dodd Date: Thu, 28 Sep 2017 14:01:56 +0000 (+0100) Subject: Add some docs X-Git-Tag: archive/raspbian/0.35.0-2+rpi1~3^2^2^2^2^2^2^2~22^2~6^2~30^2 X-Git-Url: https://dgit.raspbian.org/%22http://www.example.com/cgi/success//%22http:/www.example.com/cgi/success/?a=commitdiff_plain;h=55f56e737d1976cf55b3afdc828932345b145afe;p=cargo.git Add some docs --- diff --git a/src/cargo/ops/cargo_rustc/context.rs b/src/cargo/ops/cargo_rustc/context.rs index 219496af8..b4435f213 100755 --- a/src/cargo/ops/cargo_rustc/context.rs +++ b/src/cargo/ops/cargo_rustc/context.rs @@ -561,7 +561,7 @@ impl<'a, 'cfg> Context<'a, 'cfg> { /// and link_stem would be out_dir/foo /// This function returns it in two parts so the caller can add prefix/suffix /// to filename separately - + /// /// Returns an Option because in some cases we don't want to link /// (eg a dependent lib) pub fn link_stem(&mut self, unit: &Unit<'a>) -> Option<(PathBuf, String)> { @@ -595,9 +595,10 @@ impl<'a, 'cfg> Context<'a, 'cfg> { /// Return the filenames that the given target for the given profile will /// generate as a list of 3-tuples (filename, link_dst, linkable) - /// filename: filename rustc compiles to. (Often has metadata suffix). - /// link_dst: Optional file to link/copy the result to (without metadata suffix) - /// linkable: Whether possible to link against file (eg it's a library) + /// + /// - filename: filename rustc compiles to. (Often has metadata suffix). + /// - link_dst: Optional file to link/copy the result to (without metadata suffix) + /// - linkable: Whether possible to link against file (eg it's a library) pub fn target_filenames(&mut self, unit: &Unit<'a>) -> CargoResult, bool)>>> { if let Some(cache) = self.target_filenames.get(unit) { diff --git a/src/cargo/ops/cargo_rustc/custom_build.rs b/src/cargo/ops/cargo_rustc/custom_build.rs index ad1178800..ee51b9b3b 100644 --- a/src/cargo/ops/cargo_rustc/custom_build.rs +++ b/src/cargo/ops/cargo_rustc/custom_build.rs @@ -34,8 +34,10 @@ pub struct BuildOutput { pub warnings: Vec, } +/// Map of packages to build info pub type BuildMap = HashMap<(PackageId, Kind), BuildOutput>; +/// Build info and overrides pub struct BuildState { pub outputs: Mutex, overrides: HashMap<(String, Kind), BuildOutput>, diff --git a/src/cargo/ops/cargo_rustc/mod.rs b/src/cargo/ops/cargo_rustc/mod.rs index 3e7fdbd2f..36f59e4c9 100644 --- a/src/cargo/ops/cargo_rustc/mod.rs +++ b/src/cargo/ops/cargo_rustc/mod.rs @@ -37,26 +37,48 @@ mod layout; mod links; mod output_depinfo; +/// Whether an object is for the host arch, or the target arch. +/// +/// These will be the same unless cross-compiling. #[derive(PartialEq, Eq, Hash, Debug, Clone, Copy, PartialOrd, Ord)] pub enum Kind { Host, Target } +/// Configuration information for a rustc build. #[derive(Default, Clone)] pub struct BuildConfig { + /// The host arch triple + /// + /// e.g. x86_64-unknown-linux-gnu, would be + /// - machine: x86_64 + /// - hardware-platform: unknown + /// - operating system: linux-gnu pub host_triple: String, + /// Build information for the host arch pub host: TargetConfig, + /// The target arch triple, defaults to host arch pub requested_target: Option, + /// Build information for the target pub target: TargetConfig, + /// How many rustc jobs to run in parallel pub jobs: u32, + /// Whether we are building for release pub release: bool, + /// Whether we are running tests pub test: bool, + /// Whether we are building documentation pub doc_all: bool, + /// Whether to print std output in json format (for machine reading) pub json_messages: bool, } +/// Information required to build for a target #[derive(Clone, Default)] pub struct TargetConfig { + /// The path of archiver (lib builder) for this target. pub ar: Option, + /// The path of the linker for this target. pub linker: Option, + /// Special build options for any necessary input files (filename -> options) pub overrides: HashMap, } diff --git a/src/cargo/util/process_builder.rs b/src/cargo/util/process_builder.rs index f870c64e1..ab5de7f08 100644 --- a/src/cargo/util/process_builder.rs +++ b/src/cargo/util/process_builder.rs @@ -11,12 +11,21 @@ use shell_escape::escape; use util::{CargoResult, CargoResultExt, CargoError, process_error, read2}; use util::errors::CargoErrorKind; +/// A builder object for an external process, similar to `std::process::Command`. #[derive(Clone, Debug)] pub struct ProcessBuilder { + /// The program to execute. program: OsString, + /// A list of arguments to pass to the program. args: Vec, + /// Any environment variables that should be set for the program. env: HashMap>, + /// Which directory to run the program from. cwd: Option, + /// The `make` jobserver. See the [jobserver crate][jobserver_docs] for + /// more information. + /// + /// [jobserver_docs]: https://docs.rs/jobserver/0.1.6/jobserver/ jobserver: Option, } @@ -33,16 +42,19 @@ impl fmt::Display for ProcessBuilder { } impl ProcessBuilder { + /// (chainable) Set the executable for the process. pub fn program>(&mut self, program: T) -> &mut ProcessBuilder { self.program = program.as_ref().to_os_string(); self } + /// (chainable) Add an arg to the args list. pub fn arg>(&mut self, arg: T) -> &mut ProcessBuilder { self.args.push(arg.as_ref().to_os_string()); self } + /// (chainable) Add many args to the args list. pub fn args>(&mut self, arguments: &[T]) -> &mut ProcessBuilder { self.args.extend(arguments.iter().map(|t| { t.as_ref().to_os_string() @@ -50,6 +62,7 @@ impl ProcessBuilder { self } + /// (chainable) Replace args with new args list pub fn args_replace>(&mut self, arguments: &[T]) -> &mut ProcessBuilder { self.args = arguments.iter().map(|t| { t.as_ref().to_os_string() @@ -57,46 +70,61 @@ impl ProcessBuilder { self } + /// (chainable) Set the current working directory of the process pub fn cwd>(&mut self, path: T) -> &mut ProcessBuilder { self.cwd = Some(path.as_ref().to_os_string()); self } + /// (chainable) Set an environment variable for the process. pub fn env>(&mut self, key: &str, val: T) -> &mut ProcessBuilder { self.env.insert(key.to_string(), Some(val.as_ref().to_os_string())); self } + /// (chainable) Unset an environment variable for the process. pub fn env_remove(&mut self, key: &str) -> &mut ProcessBuilder { self.env.insert(key.to_string(), None); self } + /// Get the executable name. pub fn get_program(&self) -> &OsString { &self.program } + /// Get the program arguments pub fn get_args(&self) -> &[OsString] { &self.args } + /// Get the current working directory for the process pub fn get_cwd(&self) -> Option<&Path> { self.cwd.as_ref().map(Path::new) } + /// Get an environment variable as the process will see it (will inherit from environment + /// unless explicitally unset). pub fn get_env(&self, var: &str) -> Option { self.env.get(var).cloned().or_else(|| Some(env::var_os(var))) .and_then(|s| s) } + /// Get all environment variables explicitally set or unset for the process (not inherited + /// vars). pub fn get_envs(&self) -> &HashMap> { &self.env } + /// Set the `make` jobserver. See the [jobserver crate][jobserver_docs] for + /// more information. + /// + /// [jobserver_docs]: https://docs.rs/jobserver/0.1.6/jobserver/ pub fn inherit_jobserver(&mut self, jobserver: &Client) -> &mut Self { self.jobserver = Some(jobserver.clone()); self } + /// Run the process, waiting for completion, and mapping non-success exit codes to an error. pub fn exec(&self) -> CargoResult<()> { let mut command = self.build_command(); let exit = command.status().chain_err(|| { @@ -114,6 +142,9 @@ impl ProcessBuilder { } } + /// On unix, executes the process using the unix syscall `execvp`, which will block this + /// process, and will only return if there is an error. On windows this is a synonym for + /// `exec`. #[cfg(unix)] pub fn exec_replace(&self) -> CargoResult<()> { use std::os::unix::process::CommandExt; @@ -125,11 +156,15 @@ impl ProcessBuilder { &format!("could not execute process `{}`", self.debug_string()), None, None)))) } + /// On unix, executes the process using the unix syscall `execvp`, which will block this + /// process, and will only return if there is an error. On windows this is a synonym for + /// `exec`. #[cfg(windows)] pub fn exec_replace(&self) -> CargoResult<()> { self.exec() } + /// Execute the process, returning the stdio output, or an error if non-zero exit status. pub fn exec_with_output(&self) -> CargoResult { let mut command = self.build_command(); @@ -149,6 +184,12 @@ impl ProcessBuilder { } } + /// Execute a command, passing each line of stdout and stderr to the supplied callbacks, which + /// can mutate the string data. + /// + /// If any invocations of these function return an error, it will be propagated. + /// + /// Optionally, output can be passed to errors using `print_output` pub fn exec_with_streaming(&self, on_stdout_line: &mut FnMut(&str) -> CargoResult<()>, on_stderr_line: &mut FnMut(&str) -> CargoResult<()>, @@ -226,6 +267,8 @@ impl ProcessBuilder { Ok(output) } + /// Converts ProcessBuilder into a `std::process::Command`, and handles the jobserver if + /// present. pub fn build_command(&self) -> Command { let mut command = Command::new(&self.program); if let Some(cwd) = self.get_cwd() { @@ -246,6 +289,7 @@ impl ProcessBuilder { command } + /// Get the command line for the process as a string. fn debug_string(&self) -> String { let mut program = format!("{}", self.program.to_string_lossy()); for arg in &self.args { @@ -256,6 +300,7 @@ impl ProcessBuilder { } } +/// A helper function to create a ProcessBuilder. pub fn process>(cmd: T) -> ProcessBuilder { ProcessBuilder { program: cmd.as_ref().to_os_string(),